{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "monotone",
      "provenance": [],
      "collapsed_sections": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "ywj1qEt3-lLC"
      },
      "source": [
        "##### Copyright 2020 Google LLC.\n",
        "\n",
        "\n",
        "Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "you may not use this file except in compliance with the License.\n",
        "You may obtain a copy of the License at\n",
        "\n",
        "    https://www.apache.org/licenses/LICENSE-2.0\n",
        "\n",
        "Unless required by applicable law or agreed to in writing, software\n",
        "distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "See the License for the specific language governing permissions and\n",
        "limitations under the License."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "rcsUQKXN3Qb4",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "import matplotlib.pyplot as plt\n",
        "import numpy as np\n",
        "import pandas as pd\n",
        "\n",
        "# Tensorflow modules.\n",
        "import tensorflow as tf"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "mhe1T1Xm1oGA",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "# Install Tensorflow Lattice and Tensorflow Constrained Optimization libraries.\n",
        "!pip install tensorflow_lattice\n",
        "!pip install git+https://github.com/google-research/tensorflow_constrained_optimization"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "gHB06cJv1jsO",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "# Tensor flow lattice modules.\n",
        "import tensorflow_lattice as tfl\n",
        "\n",
        "# Tensorflow constrained optimization modules.\n",
        "import tensorflow_constrained_optimization as tfco"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "rMqd66aG3IKm",
        "colab_type": "text"
      },
      "source": [
        "## Overview"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "NV5m-FNT20OH",
        "colab_type": "text"
      },
      "source": [
        "In this notebook, we'll train a one-dimensional monotonic function with pairwise constraints for fairness.  \n",
        "\n",
        "**Problem Setup:** We will consider a simulated ranking task consisting of a set of examples represented by real-valued scores $\\{x_1, \\ldots, x_n\\}$ and a set of \"ground truth\" labels $\\{y_1, \\ldots, y_n\\}$ (with higher implying better). Each example is also associated with a binary protected group. The goal is to learn a real-valued function $f: \\mathbb{R} \\rightarrow \\mathbb{R}$ on the scores that ranks examples with higher labels above those with lower labels.  Additionally, we will impose a fairness goal on $f$ (loosely speaking, we will require $f$ to perform equally well on examples from both groups). \n",
        "<br><br>\n",
        "\n",
        "**Pairwise Fairness:** For measuring fairness, we will adopt the \"pairwise\" fairness criteria proposed in:\n",
        "> Harikrishna Narasimhan, Andrew Cotter, Maya Gupta, Serena Wang, \"Pairwise Fairness for Ranking and Regression\", AAAI 2020.\n",
        "\n",
        "Henceforth, we will refer to this paper as [NCGW19].\n",
        "<br><br>\n",
        "\n",
        "The fairness criteria in [NCGW19] are defined in terms of the group-dependent pairwise accuracy for $f$:\n",
        "$$\n",
        "Acc_{G_i > G_j}(f) \\,=\\, \\mathbb{P}( f(x) > f(x') \\mid y > y', (x,y) \\in G_i, (x',y') \\in G_j ).\n",
        "$$\n",
        "We will use a slight variant of the above definition that assigns a value of 1/2 for ties:\n",
        "$$\n",
        "Acc_{G_i > G_j}(f) \\,=\\, \\mathbb{P}( f(x) > f(x') \\mid y > y', (x,y) \\in G_i, (x',y') \\in G_j ) \\,+\\, \n",
        "\\frac{1}{2}\\mathbb{P}( f(x) = f(x') \\mid y > y', (x,y) \\in G_i, (x',y') \\in G_j ).\n",
        "$$\n",
        "\n",
        "We will also be interested in the  overall pairwise accuracy of $f$:\n",
        "$$\n",
        "A(f) \\,=\\, \\mathbb{P}( f(x) > f(x') \\mid y > y' ) \\,+\\, \\frac{1}{2}\\mathbb{P}( f(x) = f(x') \\mid y > y' ).\n",
        "$$\n",
        "<br>\n",
        "\n",
        "**Monotone Function**: We will restrict our attention to ranking functions $f$ that are monotonic in the scores $x$. While the learned monotone function cannot change the underlying ordering of examples , it can introduce ties in the ordering. As we will see, this can be helpful in enforcing our fairness goal. \n",
        "\n",
        "Throughout this notebook, we will refer to the $x$ as the original score for an example, and $f(x)$ as the prediction for the example.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "uO9o9od_EEGm",
        "colab_type": "text"
      },
      "source": [
        "## Simulated Data\n",
        "\n",
        "We generate a dataset with two groups. We generate the scores in such a way that they are more accurate for one of the groups."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "A7ztq8b0EEdP",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "np.random.seed(123456)\n",
        "\n",
        "# Generate 100 examples. Each example has a score, label and a binary group.\n",
        "num_examples = 100\n",
        "\n",
        "# Generate labels from a uniform distribution, and \n",
        "# the associated protected groups from a Bernoulli(0.5).\n",
        "labels = np.random.rand(num_examples)\n",
        "groups = (np.random.rand(num_examples) > 0.5) * 1\n",
        "\n",
        "# Generate scores by introducing Gaussian noise in the labels, \n",
        "# and scale them  to [0, 1].\n",
        "scores = labels + np.random.normal(loc=0, scale=0.05, size=num_examples)\n",
        "scores = (scores - scores.min()) / (scores.max() - scores.min())\n",
        "\n",
        "# Additional noise for group 1 examples.\n",
        "# Add uniform random noise to the group scores in the range [0.2, 0.8].\n",
        "noise_low = 0.2\n",
        "noise_high = 0.8\n",
        "noise_indices = (groups == 1) & (scores >= noise_low) & (scores <= noise_high)\n",
        "scores[noise_indices] = noise_low + (\n",
        "    np.random.rand(sum(noise_indices)) * (noise_high - noise_low))"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "uOSaHq-iT34a",
        "colab_type": "text"
      },
      "source": [
        "Let us plot the generated data."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "zHDPRJjrHLzI",
        "colab_type": "code",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 369
        },
        "outputId": "a7878972-1c30-40fc-fc8f-da6d6b81d2d7"
      },
      "source": [
        "def plot_scores(x, y, groups, ax, xlabel, ylabel):\n",
        "  # Plots x vs. y using different markers for the group0 and group1 examples.\n",
        "  ax.plot(x[groups == 0], y[groups == 0], \"ro\", label=\"Group 0\")\n",
        "  ax.plot(x[groups == 1], y[groups == 1], \"bx\", label=\"Group 1\")\n",
        "  ax.set_xlabel(xlabel)\n",
        "  ax.set_ylabel(ylabel)\n",
        "  ax.set_title(ylabel + \" vs. \" + xlabel)\n",
        "  ax.legend(loc=\"best\")\n",
        "  ff.tight_layout()\n",
        "  \n",
        "# Plot scores as a function of labels.\n",
        "ff, ax = plt.subplots(1, 1, figsize=(5, 5))\n",
        "plot_scores(labels, scores, groups, ax, \"Labels\", \"Scores\")"
      ],
      "execution_count": 5,
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "image/png": "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\n",
            "text/plain": [
              "<Figure size 360x360 with 1 Axes>"
            ]
          },
          "metadata": {
            "tags": []
          }
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Epf_7eGDUSo5",
        "colab_type": "text"
      },
      "source": [
        "Notice that the original scores order the group 0 examples accurately, but are unreliable for the group 1 examples in the range [0.2, 0.8]. \n",
        "Can we learn a monotone transform on these scores that performs equally well on both groups? For example, would we be able to improve the performance on the group 1 examples by flattening the scores in the [0.2, 0.8] range, while preserving their relative ordering in other regions?"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "klkQywh0du20",
        "colab_type": "text"
      },
      "source": [
        "## Formulate Pairs\n",
        "\n",
        "Having generated the data, we enumerate all pairs of examples $(x, x')$ where the labels $y > y'$. By creating ordered example pairs, we can now treat the ranking problem as a classification problem on pairs. "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "DVxq0hqjPQJi",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "# Create a pandas DataFrame with the data contents.\n",
        "examples_df = pd.DataFrame()\n",
        "examples_df = examples_df.assign(scores=scores, labels=labels, groups=groups, \n",
        "                                 merge_key=0)\n",
        "\n",
        "# We have an additional merge_key column, which we will use to merge the \n",
        "# data frame with itself, and enumerate all pairs of examples.\n",
        "paired_df = examples_df.merge(examples_df.copy(), on=\"merge_key\", how=\"outer\",\n",
        "                              suffixes=(\"_high\", \"_low\"))\n",
        "\n",
        "# Only retain pairs where labels_high > labels_low.\n",
        "paired_df = paired_df[paired_df.labels_high > paired_df.labels_low]\n",
        "\n",
        "# Create 2-d NumPy array containing the scores for the higher label examples\n",
        "# in the first column and the scores for lower label examples in the second \n",
        "# column. Similarly, create a 2-d NumPy array for the groups.\n",
        "paired_scores = np.stack([paired_df.scores_high.values, \n",
        "                          paired_df.scores_low.values], axis=1)\n",
        "paired_labels = np.stack([paired_df.labels_high.values, \n",
        "                          paired_df.labels_low.values], axis=1)\n",
        "paired_groups = np.stack([paired_df.groups_high.values, \n",
        "                          paired_df.groups_low.values], axis=1)"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "-XENpJ3rVd88",
        "colab_type": "text"
      },
      "source": [
        "Note that `paired_scores`  and `paired_groups` are two-dimensional arrays, where each row represents an ordered pair of example.  The first column in `paired_scores`  contains the scores for the 'high label' examples in the pairs, and the second column contains the scores for the 'low label' examples in the pairs. Similarly,  `paired_groups` contains the corresponding protected groups for the 'high label' and 'low label' examples in the pairs."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SlJnKXpEEBif",
        "colab_type": "text"
      },
      "source": [
        "## Monotone Model\n",
        "\n",
        "We next model the ranking function $f$ as a monotone, one-dimensional calibrator. We use the callibration layer provided in the TF Lattice package to construct the monotone function, and compute the difference in function values $f(x) - f(x')$ on each pair of examples $(x, x')$. The pairwise accuracies can then be computed as a classification rates on the differences in scores.\n",
        "\n",
        "For more details on 1-D calibrators, please see the following <a href=\"http://jmlr.org/papers/v17/15-243.html\"> paper</a>."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "DlhGeHOk-u1p",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "tf.reset_default_graph()\n",
        "\n",
        "# We 1-d callibrator with 100 key points. A monotone function is constructed by\n",
        "# linearly interpolating the values on these keypoints.\n",
        "num_keypoints = 100\n",
        "kp_inits = tfl.uniform_keypoints_for_signal(\n",
        "    num_keypoints=num_keypoints,\n",
        "    input_min=0.0,\n",
        "    input_max=1.0,\n",
        "    output_min=0,\n",
        "    output_max=1.0)\n",
        "\n",
        "# Placeholder tensor for holding the input scores.\n",
        "scores_tensor = tf.placeholder(tf.float32, shape=(None,), name=\"scores\")\n",
        "# We pass 1-d input array to the calibrator. Recall that we will eventually need\n",
        "# to compute scores on pairs of examples (x, x'), i.e. on the paired_scores\n",
        "# array. To do so, we will flatten paired_scores and \n",
        "# pass it as a 1-d array (where the first half contains the \"x\" scores, and the \n",
        "# second half contains the \"x'\" scores).\n",
        "\n",
        "# Predictions from the calibrator on the input scores.\n",
        "(predictions_tensor, projection_op, _) = tfl.calibration_layer(\n",
        "    uncalibrated_tensor=scores_tensor,\n",
        "    num_keypoints=num_keypoints,\n",
        "    monotonic=+1,\n",
        "    keypoints_initializers=kp_inits)\n",
        "# Setting monotonic=+1 enforces that the calibrator is monotonic.\n",
        "# Note that the returned projection_op is the projection operation for \n",
        "# enforcing monotonicity.\n",
        "\n",
        "# Since we will feed in a flattened array of scores as input, the \n",
        "# predictions_tensor will also be one dimensional. The first half of this tensor \n",
        "# will contain the scores for the \"x\" examples and the second half of the tensor \n",
        "# will contain the scores for the \"x'\" examples. We will slice the \n",
        "# predictions_tensor into two halves and compute the element-wise differences \n",
        "# in scores between the first half and the second half, i.e. f(x) - f(x').\n",
        "num_pairs = tf.cast(tf.shape(scores_tensor)[0] / 2, tf.int32)\n",
        "prediction_diffs_tensor = (predictions_tensor[:num_pairs] - \n",
        "                           predictions_tensor[num_pairs:])"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "uQFulCd0eYoE",
        "colab_type": "text"
      },
      "source": [
        "By creating ordered pairs of examples $(x, x')$, we can now frame the ranking problem as a classification task, with the goal of maximizing the fraction of examples where the difference  $f(x) - f(x')$ is positive. To this end, we define an all 1's tensor that holds the target label for each pair.\n",
        "\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "sxFETxH_eeS0",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "target_labels_tensor = tf.ones(dtype=tf.float32, shape=(num_pairs,), \n",
        "                               name=\"target_labels\")"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "z6hmxRtCehM_",
        "colab_type": "text"
      },
      "source": [
        "We will also need placeholder tensors to identify subsets of example pairs on which we wish to impose fairness constraints. For this tutorial, we will impose constraints on two subsets of example pairs. We create tensors for holding boolean predicates for identifying these subsets."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "D4kq7hwWehUJ",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "subset0_predicate = tf.placeholder(tf.bool, shape=(None,), name=\"subset0\")\n",
        "subset1_predicate = tf.placeholder(tf.bool, shape=(None,), name=\"subset1\")"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "UP-kNKX1r91z",
        "colab_type": "text"
      },
      "source": [
        "## Baseline: Original Scores"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zHEkNDtQfhxM",
        "colab_type": "text"
      },
      "source": [
        "Before proceeding to train our model, let us first evaluate the performance of the original, untransformed scores.\n",
        "Below, we provide functions for evaluating the group-dependent pairwise accuracy and the overall accuracy for given the score differences on pairs of examples."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "0AguGyzDtsPZ",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "def group_pairwise_accuracy(prediction_diffs, paired_groups):\n",
        "  \"\"\"Returns the group-dependent pairwise accuracies.\n",
        "  \n",
        "  Returns the group-dependent pairwise accuracies Acc_{G_i > G_j} for each pair \n",
        "  of groups G_i \\in {0, 1} and G_j \\in {0, 1}. \n",
        "  \n",
        "  Args:\n",
        "    prediction_diffs: NumPy array of shape (#num_pairs,) containing the \n",
        "                      differences in scores for each ordered pair of examples.\n",
        "    paired_groups: NumPy array of shape (#num_pairs, 2) containing the protected \n",
        "                   groups for the better and worse example in each pair.\n",
        "                   \n",
        "  Returns:\n",
        "    A NumPy array of shape (2, 2) containing the pairwise accuracies, where the \n",
        "    ij-th entry contains Acc_{G_i > G_j}.\n",
        "  \"\"\"\n",
        "  accuracy_matrix = np.zeros((2, 2))\n",
        "  for group_high in [0, 1]:\n",
        "    for group_low in [0, 1]:\n",
        "      # Predicate for pairs where the better example is from group_high\n",
        "      # and the worse example is from group_low.\n",
        "      predicate = ((paired_groups[:, 0] == group_high) & \n",
        "                   (paired_groups[:, 1] == group_low))\n",
        "      # Parwise accuracy Acc_{group_high > group_low}.\n",
        "      accuracy_matrix[group_high][group_low] = (\n",
        "          np.mean(prediction_diffs[predicate] > 0) + \n",
        "          0.5 * np.mean(prediction_diffs[predicate] == 0))\n",
        "  return accuracy_matrix\n",
        "\n",
        "\n",
        "def overall_pairwise_accuracy(prediction_diffs):\n",
        "  # Returns overall pairwise accuracy for pairwise differences in predictions.\n",
        "  overall_accuracy = (np.mean(prediction_diffs > 0) + \n",
        "                      0.5 * np.mean(prediction_diffs == 0))\n",
        "  return overall_accuracy"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "znx51IQosiLZ",
        "colab_type": "text"
      },
      "source": [
        "We evaluate the performance of ranking with the original scores."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "WJMMM9j1smOC",
        "colab_type": "code",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 102
        },
        "outputId": "6eeda904-a05e-49ab-a9ca-228defc81eb9"
      },
      "source": [
        "prediction_diffs = paired_scores[:, 0] - paired_scores[:, 1]\n",
        "overall_accuracy = overall_pairwise_accuracy(prediction_diffs)\n",
        "print(\"Baseline: Overall pairwise accuracy = %.3f\" % overall_accuracy)\n",
        "\n",
        "pairwise_accuracy = group_pairwise_accuracy(prediction_diffs, paired_groups)\n",
        "print(\"Baseline: Group-dependent pairwise accuracies\"\n",
        "      \"(rows=better, columns=worse)\")\n",
        "pairwise_accuracy_df = pd.DataFrame(\n",
        "    pairwise_accuracy, \n",
        "    columns=[\"Group 0\", \"Group 1\"], \n",
        "    index=[\"Group 0\", \"Group 1\"]).round(decimals=3)\n",
        "print(pairwise_accuracy_df)"
      ],
      "execution_count": 23,
      "outputs": [
        {
          "output_type": "stream",
          "text": [
            "Baseline: Overall pairwise accuracy = 0.840\n",
            "Baseline: Group-dependent pairwise accuracies(rows=better, columns=worse)\n",
            "         Group 0  Group 1\n",
            "Group 0    0.938    0.886\n",
            "Group 1    0.794    0.777\n"
          ],
          "name": "stdout"
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "aXzMDTb1y3uH",
        "colab_type": "text"
      },
      "source": [
        "Note that $Acc_{G0 > G1}$ is significantly higher than $Acc_{G1 > G0}$. This implies that the original scores are more effective in ranking the \"better\" examples from group 0 above the \"worse\" examples from group 1, when compared to ranking the \"better\" examples from group 1 above the worse examples from group 0.\n",
        "\n",
        "In the following, we will seek to remove this discrepancy by learning a monotone function on the scores under pairwise constraints for fairness."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qf9YhLi6YNHk",
        "colab_type": "text"
      },
      "source": [
        "## Proposed Approach: Constrained Optimization\n",
        "\n",
        "We seek to maximize the overall pairwise accuracy subject to the constraint that $Acc_{G1 > G0}$ and $Acc_{G0 > G1}$ can differ by at most 0.01.\n",
        "\n",
        "$$\n",
        "max_f ~~A(f) ~~~~s.t.~~~~ |Acc_{G1 > G0}(f)   ~-~ Acc_{G0 > G1}(f)| ~\\leq~ 0.01\n",
        "$$\n",
        "\n",
        "The constraint that we enforce here is a relaxation of the *cross-group pairwise equal opportunity* criteria in [NCGW19]."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "BVOjVx7zXuKL",
        "colab_type": "code",
        "colab": {}
      },
      "source": [
        "# We set up the constrained optimization problem using the TF constrained \n",
        "# optimization library. \n",
        "\n",
        "# Set up context object for the entire data \n",
        "# (for evaluating performance based on the pairwise prediction differences and \n",
        "# and the target labels).\n",
        "context_overall = tfco.rate_context(prediction_diffs_tensor, \n",
        "                                    target_labels_tensor)\n",
        "# Set up context objects for the subsets: \n",
        "# G0>G1 pairs denoted as subset0 and G1>G0 pairs denoted as subset1.\n",
        "context_subset0 = context_overall.subset(subset0_predicate)\n",
        "context_subset1 = context_overall.subset(subset1_predicate)\n",
        "# The subset predicates will be fed in during training.\n",
        "\n",
        "# Set up the objective and constraints in terms of error rates.\n",
        "# (while the definitions in the notebook used \"accuracy rates\", we will find\n",
        "# it convenient in the implementation to instead use \"error rates\")\n",
        "# The objective is to minimize the error rate on all pairs.\n",
        "objective = tfco.error_rate(context_overall)\n",
        "# Since the target labels are all 1's, minimizing the error rate on the \n",
        "# prediction differences is the same as maximizing overall pairwise accuracy.\n",
        "constraints = [\n",
        "    tfco.error_rate(context_subset0) <= tfco.error_rate(context_subset1) + 0.01,\n",
        "    tfco.error_rate(context_subset1) <= tfco.error_rate(context_subset0) + 0.01]\n",
        "# We constrain the difference between the error rate on the G0>G1 pairs and the\n",
        "# error rate on the G1>G0 pairs to be within 0.01\n",
        "# (this is equivalent to constraining the accuracy rates on the two subsets).\n",
        "\n",
        "# Set up a rate minimization problem.\n",
        "problem = tfco.RateMinimizationProblem(objective, constraints)\n",
        "\n",
        "# Set up the optimizer and get `train_op` for gradient updates.\n",
        "solver = tf.train.AdamOptimizer(learning_rate=0.1)\n",
        "optimizer = tfco.ProxyLagrangianOptimizerV1(optimizer=solver)\n",
        "train_op = optimizer.minimize(problem)"
      ],
      "execution_count": 0,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "DbNQZoSe62jS",
        "colab_type": "text"
      },
      "source": [
        "We are now ready to train our model (this may take a few seconds to run)."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "O7BedJDRZB4E",
        "colab_type": "code",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 102
        },
        "outputId": "5ee15252-8a51-4288-ce7f-bcb260938ed3"
      },
      "source": [
        "# Start TF session and initialize variables.\n",
        "session = tf.Session()\n",
        "tf.set_random_seed(654321)  # Set random seed for reproducibility.\n",
        "session.run(tf.global_variables_initializer())\n",
        "\n",
        "# Dictionary of values to be fed to the placeholder tensors.\n",
        "feed_dict = {\n",
        "    scores_tensor: paired_scores.T.reshape(-1,),\n",
        "    subset0_predicate: (paired_groups[:, 0] == 0) & (paired_groups[:, 1] == 1),\n",
        "    subset1_predicate: (paired_groups[:, 0] == 1) & (paired_groups[:, 1] == 0)\n",
        "}\n",
        "# Scores: As mentioned earlier, we flatten the paired_scores so that the scores \n",
        "# for the higher label (better) examples in the pairs are arranged first, and \n",
        "# those for the lower label (worse) examples in the pairs come next.\n",
        "# Predicates: subset0_predicate select pairs where the better example\n",
        "# is from group 0 and the worse example is from group 1. subset1_predicate \n",
        "# select pairs where the better example is from group 1 and the worse\n",
        "# example is from group 0.\n",
        "\n",
        "# We maintain a list of objectives, constraint violations, predictions and \n",
        "# overall accuracies, and pairwise accuracies during the course of training.\n",
        "objectives = []\n",
        "violations = []\n",
        "predictions = []\n",
        "overall_accuracies = []\n",
        "pairwise_accuracies = []\n",
        "\n",
        "# Perform 250 full gradient updates.\n",
        "for ii in range(250):\n",
        "  # Gradient updates.\n",
        "  session.run(train_op, feed_dict=feed_dict)\n",
        "  # Projection step.\n",
        "  session.run(projection_op)\n",
        "  # Checkpoint once in 10 iterations.\n",
        "  if ii % 10 == 0:\n",
        "    # Objective and constraint violations.\n",
        "    objective, violation = session.run(\n",
        "        (problem.objective(), problem.constraints()), feed_dict=feed_dict)\n",
        "    objectives.append(objective)\n",
        "    violations.append(violation)\n",
        "    \n",
        "    # Pairwise prediction differences and overall and group pairwise accuracies.\n",
        "    prediction_diffs = session.run(\n",
        "        prediction_diffs_tensor, \n",
        "        feed_dict={scores_tensor: paired_scores.T.reshape(-1,)}) \n",
        "    # Note that we feed in the \"paired\" scores, flattened to a 1-d array.\n",
        "    overall_acc = overall_pairwise_accuracy(prediction_diffs)\n",
        "    overall_accuracies.append(overall_acc)\n",
        "    pairwise_acc = group_pairwise_accuracy(prediction_diffs, paired_groups)\n",
        "    pairwise_accuracies.append(pairwise_acc)\n",
        "    \n",
        "    # Predictions on individual examples \n",
        "    # (needed later for plotting the trained monotone function).\n",
        "    prediction = session.run(predictions_tensor, \n",
        "                             feed_dict={scores_tensor: scores})\n",
        "    # Note that we feed in the individual scores (not the paired ones).\n",
        "    predictions.append(prediction)\n",
        "    \n",
        "session.close()\n",
        "    \n",
        "# Use the recorded objectives and constraints to find the best iterate.\n",
        "best_iterate = tfco.find_best_candidate_index(np.array(objectives),\n",
        "                                              np.array(violations))\n",
        "\n",
        "print(\"Constrained Opt: Overall pairwise accuracy = %.3f\" \n",
        "      % overall_accuracies[best_iterate])\n",
        "print(\"Constrained Opt: Group-dependent pairwise accuracies\"\n",
        "      \"(rows=better, columns=worse)\")\n",
        "pairwise_accuracies_df = pd.DataFrame(\n",
        "    pairwise_accuracies[best_iterate], \n",
        "    columns=[\"Group 0\", \"Group 1\"], \n",
        "    index=[\"Group 0\", \"Group 1\"]).round(decimals=3)\n",
        "print(pairwise_accuracies_df)"
      ],
      "execution_count": 27,
      "outputs": [
        {
          "output_type": "stream",
          "text": [
            "Constrained Opt: Overall pairwise accuracy = 0.840\n",
            "Constrained Opt: Group-dependent pairwise accuracies(rows=better, columns=worse)\n",
            "         Group 0  Group 1\n",
            "Group 0    0.905    0.853\n",
            "Group 1    0.842    0.785\n"
          ],
          "name": "stdout"
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SD5bKu1AHf84",
        "colab_type": "text"
      },
      "source": [
        "By imposing explict constraints, we are able to ensure that the cross-group pairwise accuracies are within 0.01 of each other. The trained monotone function achieves this by improving on the accuracy for the $G_1 > G_0$ pairs but at the cost of lowering the accuracy for the $G_0 > G_1$ pairs. The overall accuracy is similar to the original untransformed scores.\n",
        "\n",
        "\n",
        "We plot the learned monotone function $f(x)$ as a function of the scores $x$ and as a function of the ground-truth labels $y$."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "5SJgJAjoaevF",
        "colab_type": "code",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 369
        },
        "outputId": "a876e8ea-5d0a-441d-e762-e7c6a21470f7"
      },
      "source": [
        "ff, ax = plt.subplots(1, 2, figsize=(10, 5))\n",
        "plot_scores(scores, predictions[best_iterate], groups, ax[0], \n",
        "            \"Scores\", \"Predictions\")\n",
        "plot_scores(labels, predictions[best_iterate], groups, ax[1], \n",
        "            \"Labels\", \"Predictions\")\n",
        "ff.tight_layout()"
      ],
      "execution_count": 28,
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "image/png": "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\nW/24447znTt3+uc//3k/7LDDfNasWX7NNde4u3symfRTTjllYL1PfvKTfuWVV7q7eyKR8AsuuMBn\nzZrlLS0t/vDDDw/bz9KlS/2HP/zhwPjb3vY2f+qpp4Ytl9frBSCj3l73xsbgMdN4LiT1e4z5Gx3I\nYrIYqETFzOJYzyC7+5Ph47OS1kuaU9QdrlwpbduWPm3btmD6GN1///06+uijR1zmzjvv1I9//GPd\ncsst+slPfqK7775b99xzjzZs2KALLrhATz/99Kj7aWho0H333adPfepTWrZs2bD5Tz75pA488MCB\n8QMOOEBPPvlk/gcEYFStrVJPj7RggXTRRcFjT08wvRKRxWQxUImKmcWxFchmVm9mu6WeSzpR0m+K\nutMnnshv+hh88pOf1JFHHqmWlpaBaSeccIL22GMPSdJtt92mRYsWaeLEidp77731nve8R319faNu\nd9GiRQOPt99+e8HaC2BsWlultjbpkkuCx0otjslishioZMXK4jjPIO8t6TYzu0fSryX93N3/q6h7\nnDkzv+k5OOyww9Iuwrj88st18803K9pHr76+ftTtTJo0STt37hwYH3qPzOhtgTLdImj//ffXH/7w\nh4HxLVu2aP/998/tIADkLZmU1qyR2tuDx6H94CoIWRxBFgOVpVhZHFuB7O6PuvuR4XCYu68u+k5X\nr5bq6tKn1dUF08fo+OOP12uvvaY1a9YMTNs29KvDiLlz5+raa6/Vjh07tHXrVt16662aM2eOEomE\nHnjgAb3++ut68cUXdfPNN6etd+211w48HnvsscO2e/rpp+uqq66Su+uOO+5QQ0OD9t133zEfF4Ds\nksnBr/JWrRr8iq8Si2SymCwGKlUxs7gc7oNcOosXB48rVwZf5c2cGQRyavoYmJmuu+46feYzn1Fn\nZ6f23HNP1dfXq6OjI+PyZ555pm6//XYdeeSRMjN1dnZqn332kSQtWLBAs2bN0kEHHaSjjjoqbb0X\nXnhBRxxxhKZOnaqrr7562HZPPvlk3XjjjTrkkENUV1enK6+8cszHBGBkfX3p/dxS/eD6+iq3q0VJ\nkcUACqCYWWzBBXyVobm52fv7+9OmPfjggzr00ENjalFpNDU1qb+/X42NjePeVi28XkAlMLNNPsZf\nrIsbWUwWA9UiWxbHfR9kAAAAoKzUVheLCvX444/H3QQAqHlkMVA7OIMMAAAARFAgAwAAABEUyAAA\n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\nB8cMhdBmoNRNAAAAAElFTkSuQmCC\n",
            "text/plain": [
              "<Figure size 720x360 with 2 Axes>"
            ]
          },
          "metadata": {
            "tags": []
          }
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XOpkD9_3I9uR",
        "colab_type": "text"
      },
      "source": [
        "The monotone function flattens out portions of the scores in the middle range $[0.2, 0.8]$ (here the scores are noisy for group 1). This has the effect of introducing ties among the examples in this region, and thus improving the value of $Acc_{G_1 > G0}$, while lowering the $Acc_{G_0 > G1}$ value."
      ]
    }
  ]
}